Defining the Dialog Box Controls

The first step in creating a new VectorScript custom dialog box is to define the dialog box window and its basic properties. To do this, we will use the custom dialog box API function CreateLayout(), which creates the dialog box window and defines the title, default button, and help display properties of the dialog box. CreateLayout() then returns an identifier which will be used to add controls to the dialog box. This identifier is also used elsewhere in the script to refer to the dialog box for control positioning and event handling.

Example:

id := CreateLayout('Revise Layer Link',TRUE,'Update','Cancel');

The function creates a new empty dialog box, entitled Revise Layer Link, which contains a help text area and two default buttons (Update and Cancel). The following script creates the dialog box:

procedure CreateDialog;

VAR

id: LONGINT;

result : LONGINT;

BEGIN

id := CreateLayout(’Revise Layer Link’, TRUE, ’Update’, ’Cancel’);

result := RunLayoutDialog(id,NIL);

END;

RUN(CreateDialog);

This is the basic dialog box container in which the rest of the dialog box definition will be created.

CreateLayout() allows you some flexibility in creating the dialog box container. If, for instance, you do not wish to provide help text in a dialog box (in a confirmation dialog box, for example) you can suppress the help text area by specifying FALSE in the help text display parameter of CreateLayout(). Create Resizable Layout( ) can be used to create a resizable dialog box.

Dialog box buttons can also be suppressed if not needed. Using the example, if the dialog box did not require a Cancel button, you could suppress it simply by specifying a blank string for the button parameter:

id := CreateLayout('Revise Layer Link',FALSE,'Update','');

The default button for the dialog box can also be suppressed in this fashion:

id := CreateLayout('Revise Layer Link',FALSE,'','Cancel');

It is possible to suppress both default buttons for a dialog box. In this instance, if your code does not provide some alternate means of dismissing the dialog box, you will be unable to exit it.

Once you have defined the dialog box and its basic properties, you can begin adding the controls to it. A control is added to a custom dialog box by calling the appropriate definition function for the control, referencing the dialog box in which the control will be displayed using the identifier supplied by CreateLayout(). In our example, we will be adding a pulldown menu to display layers that can be selected for the link, controls to let us specify link properties, as well as some additional controls for descriptive text and to organize the dialog box. The resulting code is shown below:

 

procedure CreateDialog;

VAR

id: LONGINT;

result : LONGINT;

BEGIN

id := CreateLayout('Revise Layer Link',TRUE,'Update', 'Cancel');

CreateStaticText(id,4,'Relink to:',-1);

CreatePulldownMenu(id,5,32);

CreateGroupBox(id,6,'Link Options',TRUE);

CreateCheckBox(id,7,'Link object is locked');

CreateCheckBox(id,8,'Name Link:');

CreateEditText(id,9,'Untitled Link',26);

SetFirstLayoutItem(id, 4);

SetBelowItem (id,4,6,0,0);

SetFirstGroupItem(id,6,7);

SetBelowItem (id,7,5,0,0);

SetBelowItem (id,5,8,0,0);

SetBelowItem (id,8,9,0,0);

result := RunLayoutDialog(id,NIL);

END;

RUN(CreateDialog);

Each control that will be a part of the dialog box is defined with a call to a definition function. The definition for each control specifies the dialog box in which it should appear, a unique number identifying the control, and the default properties for the control. The pulldown menu, for example, is created using the function CreatePulldownMenu(), specifying the control ID of 5 and a width of 32 characters. The Set items specify the order and location of the identified controls (see Defining the Dialog Box Layout).

Once the controls have been defined, you can optionally add help text for some or all controls. Help text provides the user with an easy means of identifying what a control does from within the dialog box, and is usually recommended for all but the most basic dialog boxes.

The function SetHelpString() is used to add help for a specific control. The function associates a help string with a control; if the cursor is moved over the control when the dialog box is displayed, the associated help string will automatically be displayed in the help text area of the dialog box. The dialog box control definition code for the help strings is shown below:

 

SetHelpString(1,'Update the selected layer link.');

SetHelpString(2,'Cancel the operation and exit.');

SetHelpString(4,'New layer to be displayed by selected link.');

SetHelpString(5,'New layer to be displayed by selected link.');

SetHelpString(7,'Lock the link object after it has been updated.');

SetHelpString(8,'Apply an object name to the layer link.');

SetHelpString(9,'Apply an object name to the layer link.');

In the example, note that we have repeated certain help text strings. We did this in order to provide useful help for the item whether the cursor was over the actual control or over the label associated with the control. Also, help text was omitted for the group box control; group boxes do not have associated help text.